<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>mq_open</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_750">&nbsp;</a>NAME</h4><blockquote>
mq_open - open a message queue
(<b>REALTIME</b>)
</blockquote><h4><a name = "tag_000_007_751">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="mqueue.h.html">mqueue.h</a>&gt;

mqd_t mq_open(const char *<i>name</i>, int <i>oflag</i>, ...);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_752">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>mq_open()</i>
function establishes the connection between a process and a message queue
with a message queue descriptor.
It creates a open message queue description
that refers to the message queue, and a message queue descriptor
that refers to that open message queue description.
The message queue descriptor is used by other functions to refer
to that message queue.
The
<i>name</i>
argument points to a string naming a message queue.
It is unspecified whether the name appears in the file system
and is visible to other functions that take pathnames as arguments.
The
<i>name</i>
argument conforms to the construction rules for a pathname.
If
<i>name</i>
begins with the slash character, then processes calling
<i>mq_open()</i>
with the same value of
<i>name</i>
refer to the same message queue object,
as long as that name has not been removed.
If
<i>name</i>
does not begin with the slash
character, the effect is implementation-dependent.
The interpretation of slash
characters other than the leading slash character in
<i>name</i>
is implementation-dependent.
If the
<i>name</i>
argument is not the name of an existing message queue
and creation is not requested,
<i>mq_open()</i>
fails and returns an error.
<p>
The
<i>oflag</i>
argument requests the desired receive and/or send access to the message queue.
The requested access permission to receive messages or send messages
is granted if the calling process would be granted read or write access,
respectively, to an equivalently protected file.
<p>
The value of
<i>oflag</i>
is the bitwise inclusive OR of values from the following list.
Applications specify exactly one of the first three
values (access modes) below in the value of
<i>oflag</i>:
<dl compact>

<dt>O_RDONLY<dd>
Open the message queue for receiving messages.
The process can use the returned message queue descriptor with
<i><a href="mq_receive.html">mq_receive()</a></i>,
but not
<i><a href="mq_send.html">mq_send()</a></i>.
A message queue may be open multiple times in the same or different
processes for receiving messages.

<dt>O_WRONLY<dd>
Open the queue for sending messages.
The process can use the returned message queue descriptor with
<i><a href="mq_send.html">mq_send()</a></i>
but not
<i><a href="mq_receive.html">mq_receive()</a></i>.
A message queue may be open multiple times in the same or different
processes for sending messages.

<dt>O_RDWR<dd>
Open the queue for both receiving and sending messages.
The process can use any of the functions allowed for
O_RDONLY and O_WRONLY.
A message queue may be open multiple times in the same or different
processes for sending messages.

</dl>
<p>
Any combination of the remaining flags may be specified in the
value of
<i>oflag</i>:
<dl compact>

<dt>O_CREAT<dd>
This option is used to create a message queue,
and it requires two additional arguments:
<i>mode</i>,
which is of type
<b>mode_t</b>,
and
<i>attr</i>,
which is a pointer to a
<b>mq_attr</b>
structure.
If the pathname,
<i>name</i>,
has already been used to create a message queue that still exists,
then this flag has no effect, except as noted under O_EXCL.
Otherwise, a message queue is created without any messages in it.
The user ID of the message queue is set
to the effective user ID of the process,
and the group ID of the message queue is set
to the effective group ID of the process.
The file permission bits are set to the value of
<i>mode</i>.
When bits in
<i>mode</i>
other than file permission bits are set,
the effect is implementation-dependent.
If
<i>attr</i>
is NULL, the message queue is created
with implementation-dependent default message queue attributes.
If
<i>attr</i>
is non-NULL and the calling process has the appropriate privilege on
<i>name</i>,
the message queue
<i>mq_maxmsg</i>
and
<i>mq_msgsize</i>
attributes are set
to the values of the corresponding members in the
<b>mq_attr</b>
structure referred to by
<i>attr</i>.
If
<i>attr</i>
is non-NULL, but the calling process does not have the appropriate 
privilege on
<i>name</i>,
the
<i>mq_open()</i>
function fails and returns an error without creating the message queue.

<dt>O_EXCL<dd>
If O_EXCL and O_CREAT are set,
<i>mq_open()</i>
fails if the message queue
<i>name</i>
exists.
The check for the existence of the message queue
and the creation of the message queue
if it does not exist are atomic with respect to other processes executing
<i>mq_open()</i>
naming the same
<i>name</i>
with O_EXCL and O_CREAT set.
If O_EXCL is set and O_CREAT
is not set, the result is undefined.

<dt>O_NONBLOCK<dd>
The setting of this flag is associated with the open message queue
description
and determines whether a
<i><a href="mq_send.html">mq_send()</a></i>
or
<i><a href="mq_receive.html">mq_receive()</a></i>
waits for resources or messages that are not
currently available, or fails with
<i>errno</i>
set to [EAGAIN].
See
<i><a href="mq_send.html">mq_send()</a></i>
and
<i><a href="mq_receive.html">mq_receive()</a></i>
for details.

</dl>
<p>
The
<i>mq_open()</i>
function does not add or remove messages from the queue.
</blockquote><h4><a name = "tag_000_007_753">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
the function returns a message queue descriptor.
Otherwise, the function returns (<b> mqd_t</b> )-1
and sets
<i>errno</i>
to indicate the error.
</blockquote><h4><a name = "tag_000_007_754">&nbsp;</a>ERRORS</h4><blockquote>
The 
<i>mq_open()</i>
function will fail if:
<dl compact>

<dt>[EACCES]<dd>
The message queue
exists and the permissions specified by
<i>oflag</i>
are denied, or
the message queue
does not exist and permission to create
the message queue
is denied.

<dt>[EEXIST]<dd>
O_CREAT and O_EXCL are set and
the named message queue already exists.

<dt>[EINTR]<dd>
The
<i>mq_open()</i>
operation was interrupted by a signal.

<dt>[EINVAL]<dd>
The
<i>mq_open()</i>
operation is not supported for the given name.

<dt>[EINVAL]<dd>O_CREAT was specified in
<i>oflag</i>,
the value of
<i>attr</i>
is not NULL, and either
<i>mq_maxmsg</i>
or
<i>mq_msgsize</i>
was less than or equal to zero.

<dt>[EMFILE]<dd>
Too many message queue descriptors or
file descriptors are currently in use by this process.

<dt>[ENAMETOOLONG]<dd>

The length of the
<i>name</i>
string exceeds {PATH_MAX},
or a pathname component is longer than
{NAME_MAX} while _POSIX_NO_TRUNC is in effect.

<dt>[ENFILE]<dd>
Too many message queues
are currently open in the system.

<dt>[ENOENT]<dd>
O_CREAT is not set and the named message queue
does not exist.

<dt>[ENOSPC]<dd>
There is insufficient space for the creation of the new
message queue.

<dt>[ENOSYS]<dd>
The function
<i>mq_open()</i>
is not supported by this implementation.

</dl>
</blockquote><h4><a name = "tag_000_007_755">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_756">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_757">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="mq_close.html">mq_close()</a></i>,
<i><a href="mq_receive.html">mq_receive()</a></i>,
<i><a href="mq_send.html">mq_send()</a></i>,
<i><a href="mq_setattr.html">mq_setattr()</a></i>,
<i><a href="mq_getattr.html">mq_getattr()</a></i>,
<i><a href="mq_unlink.html">mq_unlink()</a></i>,
<i><a href="mqueue.h.html">&lt;mqueue.h&gt;</a></i>,
<i><a href="msgctl.html">msgctl()</a></i>,
<i><a href="msgget.html">msgget()</a></i>,
<i><a href="msgrcv.html">msgrcv()</a></i>,
<i><a href="msgsnd.html">msgsnd()</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

